/*
 * topological-hex, a program to compute combinatorial hexahedral meshes.
 *
 * Copyright (C) <2018> <Université catholique de Louvain (UCL), Belgique>
 *
 * List of the contributors to the development, description and complete
 * License: see LICENSE file.
 *
 * This program (topological-hex) is free software:
 * you can redistribute it and/or modify it under the terms
 * of the GNU General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program (see COPYING file).  If not,
 * see <http://www.gnu.org/licenses/>.
 */

#ifndef PARALLEL_DFS_H_
#define PARALLEL_DFS_H_

#include "solver.h"
#include "symmetry.h"

/**
 * @addtogroup dfs
 * @{
 */

/**
 * Searches for hexahedral mesh by exploring the entire search tree using a
 * parallel depth-first search.
 *
 * Parallelization is accomplished by using a breadth first search to create an
 * initial selection of problems which are then statically distributed between
 * all worker threads.
 *
 * @param cb Function called when a solution is found
 * @param user_data Pointer to arbitrary data. This value is passed to the
 *   callback whenever it is called.
 */
error_code solver_run_parallel(
  solver *solver, solver_callback cb, void *user_data);

/**
 * @}
 */

/**
 * @addtogroup distributed
 * @{
 */

/**
 * Function called to log messages on the client-side during distributed
 * computations.
 */
typedef void (*client_log)(const char *message, void *data);

/**
 * Runs a distributed client which will send the initial subproblem to the
 * server.
 *
 * Only one of the clients that connect to a given server should use this
 * function. After this client has sent the initial problem, all other clients,
 * most of which connect using @ref solver_run_distributed_client, can receive
 * their subproblems from the server.
 *
 * @param server_name Hostname of the server to connect to
 *
 * @param log Function called to log messages
 * @param log_data Pointer to user data passed to @p log
 *
 * @param chunk_size How many subproblems to request from the server when asking
 *   for more. Faster machines should use larger chunk sizes.
 * @param num_subproblems How many subproblems to create. When more machines are
 *   connected to the server, the problem needs to be subdivided more to
 *   distribute work equally across all workers.
 */
error_code solver_run_distributed(solver *solver, const char *server_name,
                                  client_log log, void *log_data,
                                  uint32_t chunk_size,
                                  uint32_t num_supbroblems);

/**
 * Runs a distributed client which receives input from the server.
 *
 * Client which run this function do not need to load any input file, as they
 * will receive all necessary information from the server.
 *
 * @param server_name Hostname of the server to connect to
 * @param log Function called to log messages
 * @param log_data Pointer to user data passed to @p log
 * @param chunk_size How many subproblems to request from the server when asking
 *   for more. Faster machines should use larger chunk sizes.
 */
error_code solver_run_distributed_client(const char *server_name,
                                         client_log log, void *log_data,
                                         uint32_t chunk_size);

/**
 * @}
 */

#endif
